 | The Web Dashboard Plugin API is not yet stabilised. If you do write your own plugins it is recommended that you subscribe to the CCNet Checkins Mailing list and watch for changes to the Dashboard project |
The Web Dashboard supports custom plugins. This page is documentation for developing your own Dashboard plugins.
First of all, you need to decide what type of plugin you are developing:- A Farm Plugin is used when you have not specified any particular project or server to view. Farm plugins therefore appear in the 'default' view of the Dashboard.
- A Server Plugin is used when you are looking at a specific server, but not any particular project.
- A Project Plugin is used when you are looking at a specific project, but not a particular build.
- A Build Plugin is used when you are viewing a specific build for a specific project.
Actions
About Actions
The CruiseControl.NET Web Dashboard includes its own Web Framework implementation. The fundamental 'component' in this framework is an Action. An Action represents a specific interraction between the application and a user. Some features require multiple actions, e.g. one Action to allow a user to edit some fields, and then another to show the results of this.Your Dashboard Plugin must include at least 1 Action. It can include more than 1, but only 1 will ever be linked directly from the Dashboard menus (the others must be linked by your other actions.)
Implementing Actions
The Actions you write should implement ICruiseAction. This has one method on it:
- IView Execute(ICruiseRequest cruiseRequest)
The responsibilty of an Action's Execute method is 'Given a request, generate a response'. The response is the 'main panel' part of the Dashboard's UI.
Defining dependencies
The CruiseControl.NET Web Dashboard uses a Constructor Dependency Injection (CDI) pattern to enable classes to define what types they are dependent on. The Dashboard API has a number of types you can depend upon which can do things like return you the currently viewed build log. You can also specify dependencies to your own types. It is recommended that you use interfaces to define responsibilities.
The Dashboard's CDI implementation does not currently allow for runtime configuration. It will use sensible defaults where available. We plan on adding more configuration later.How to start
To implement your own actions, its probably best to first look at the source code for the Dashboard's own plugins. These are available in the ThoughtWorks.CruiseControl.WebDashboard.Plugins Namespace.Support Class
Once you've written your action(s), your Plugin is almost complete, but you have one more interface, IPlugin, to implement. For simple , single-action, plugins you can just implement this interface on the same class as your action, otherwise it must be implemented on another (single) class.IPlugin contains the following properties:
- LinkDescription { get; } – Specifies the text that appears in the Dashboard UI to link to this plugin
- INamedAction[] NamedActions { get; }
The Actions property returns instances of all the Actions in your plugin. An Action is specified (in a INamedAction) by giving the action instance itself, and also a (unique) Action Name that will be used by the Web Framework's controller to route user requests. Action Names should just include alpha-numberic characters (i.e. only a-z, A-Z, and 0-9).
The Actions property must return an array with at least one INamedAction.
The first named action, i.e. Actions[0] will be the Action linked to through the Dashboard UI.For all of this look at existing implementations to see how CruiseControl.NET defines its own plugins.
Build Plugins
Build Plugins have a slight complication, in that they must implement the slightly richer interface IBuildPlugin rather than IPlugin. Most Build Plugins will do this by extending the ProjectConfigurableBuildPlugin class, which automatically makes them a Project Configurable Build Plugin - simple! 
Deploying your Plugin
To deploy your plugin:- Compile your plugin to an assembly with the name ccnet.anything-you-like.plugin.dll
- Copy the assembly to the bin folder of the Dashboard
- Configure your plugin in the Plugins Configuration Block as normal
